<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
    "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta name="generator" content="AsciiDoc 8.2.1" />
<style type="text/css">
/* Debug borders */
p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
/*
  border: 1px solid red;
*/
}

body {
  margin: 1em 5% 1em 5%;
}

a {
  color: blue;
  text-decoration: underline;
}
a:visited {
  color: fuchsia;
}

em {
  font-style: italic;
}

strong {
  font-weight: bold;
}

tt {
  color: navy;
}

h1, h2, h3, h4, h5, h6 {
  color: #527bbd;
  font-family: sans-serif;
  margin-top: 1.2em;
  margin-bottom: 0.5em;
  line-height: 1.3;
}

h1 {
  border-bottom: 2px solid silver;
}
h2 {
  border-bottom: 2px solid silver;
  padding-top: 0.5em;
}

div.sectionbody {
  font-family: serif;
  margin-left: 0;
}

hr {
  border: 1px solid silver;
}

p {
  margin-top: 0.5em;
  margin-bottom: 0.5em;
}

pre {
  padding: 0;
  margin: 0;
}

span#author {
  color: #527bbd;
  font-family: sans-serif;
  font-weight: bold;
  font-size: 1.1em;
}
span#email {
}
span#revision {
  font-family: sans-serif;
}

div#footer {
  font-family: sans-serif;
  font-size: small;
  border-top: 2px solid silver;
  padding-top: 0.5em;
  margin-top: 4.0em;
}
div#footer-text {
  float: left;
  padding-bottom: 0.5em;
}
div#footer-badges {
  float: right;
  padding-bottom: 0.5em;
}

div#preamble,
div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
div.admonitionblock {
  margin-right: 10%;
  margin-top: 1.5em;
  margin-bottom: 1.5em;
}
div.admonitionblock {
  margin-top: 2.5em;
  margin-bottom: 2.5em;
}

div.content { /* Block element content. */
  padding: 0;
}

/* Block element titles. */
div.title, caption.title {
  font-family: sans-serif;
  font-weight: bold;
  text-align: left;
  margin-top: 1.0em;
  margin-bottom: 0.5em;
}
div.title + * {
  margin-top: 0;
}

td div.title:first-child {
  margin-top: 0.0em;
}
div.content div.title:first-child {
  margin-top: 0.0em;
}
div.content + div.title {
  margin-top: 0.0em;
}

div.sidebarblock > div.content {
  background: #ffffee;
  border: 1px solid silver;
  padding: 0.5em;
}

div.listingblock {
  margin-right: 0%;
}
div.listingblock > div.content {
  border: 1px solid silver;
  background: #f4f4f4;
  padding: 0.5em;
}

div.quoteblock > div.content {
  padding-left: 2.0em;
}

div.attribution {
  text-align: right;
}
div.verseblock + div.attribution {
  text-align: left;
}

div.admonitionblock .icon {
  vertical-align: top;
  font-size: 1.1em;
  font-weight: bold;
  text-decoration: underline;
  color: #527bbd;
  padding-right: 0.5em;
}
div.admonitionblock td.content {
  padding-left: 0.5em;
  border-left: 2px solid silver;
}

div.exampleblock > div.content {
  border-left: 2px solid silver;
  padding: 0.5em;
}

div.verseblock div.content {
  white-space: pre;
}

div.imageblock div.content { padding-left: 0; }
div.imageblock img { border: 1px solid silver; }
span.image img { border-style: none; }

dl {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
}
dt {
  margin-top: 0.5em;
  margin-bottom: 0;
  font-style: italic;
}
dd > *:first-child {
  margin-top: 0;
}

ul, ol {
    list-style-position: outside;
}
ol.olist2 {
  list-style-type: lower-alpha;
}

div.tableblock > table {
  border: 3px solid #527bbd;
}
thead {
  font-family: sans-serif;
  font-weight: bold;
}
tfoot {
  font-weight: bold;
}

div.hlist {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
}
div.hlist td {
  padding-bottom: 5px;
}
td.hlist1 {
  vertical-align: top;
  font-style: italic;
  padding-right: 0.8em;
}
td.hlist2 {
  vertical-align: top;
}

@media print {
  div#footer-badges { display: none; }
}

div#toctitle {
  color: #527bbd;
  font-family: sans-serif;
  font-size: 1.1em;
  font-weight: bold;
  margin-top: 1.0em;
  margin-bottom: 0.1em;
}

div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
  margin-top: 0;
  margin-bottom: 0;
}
div.toclevel2 {
  margin-left: 2em;
  font-size: 0.9em;
}
div.toclevel3 {
  margin-left: 4em;
  font-size: 0.9em;
}
div.toclevel4 {
  margin-left: 6em;
  font-size: 0.9em;
}
/* Workarounds for IE6's broken and incomplete CSS2. */

div.sidebar-content {
  background: #ffffee;
  border: 1px solid silver;
  padding: 0.5em;
}
div.sidebar-title, div.image-title {
  font-family: sans-serif;
  font-weight: bold;
  margin-top: 0.0em;
  margin-bottom: 0.5em;
}

div.listingblock div.content {
  border: 1px solid silver;
  background: #f4f4f4;
  padding: 0.5em;
}

div.quoteblock-content {
  padding-left: 2.0em;
}

div.exampleblock-content {
  border-left: 2px solid silver;
  padding-left: 0.5em;
}

/* IE6 sets dynamically generated links as visited. */
div#toc a:visited { color: blue; }
</style>
<script type="text/javascript">
/*<![CDATA[*/
window.onload = function(){generateToc(2)}
/* Author: Mihai Bazon, September 2002
 * http://students.infoiasi.ro/~mishoo
 *
 * Table Of Content generator
 * Version: 0.4
 *
 * Feel free to use this script under the terms of the GNU General Public
 * License, as long as you do not remove or alter this notice.
 */

 /* modified by Troy D. Hanson, September 2006. License: GPL */
 /* modified by Stuart Rackham, October 2006. License: GPL */

function getText(el) {
  var text = "";
  for (var i = el.firstChild; i != null; i = i.nextSibling) {
    if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
      text += i.data;
    else if (i.firstChild != null)
      text += getText(i);
  }
  return text;
}

function TocEntry(el, text, toclevel) {
  this.element = el;
  this.text = text;
  this.toclevel = toclevel;
}

function tocEntries(el, toclevels) {
  var result = new Array;
  var re = new RegExp('[hH]([2-'+(toclevels+1)+'])');
  // Function that scans the DOM tree for header elements (the DOM2
  // nodeIterator API would be a better technique but not supported by all
  // browsers).
  var iterate = function (el) {
    for (var i = el.firstChild; i != null; i = i.nextSibling) {
      if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
        var mo = re.exec(i.tagName)
        if (mo)
          result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
        iterate(i);
      }
    }
  }
  iterate(el);
  return result;
}

// This function does the work. toclevels = 1..4.
function generateToc(toclevels) {
  var toc = document.getElementById("toc");
  var entries = tocEntries(document.getElementsByTagName("body")[0], toclevels);
  for (var i = 0; i < entries.length; ++i) {
    var entry = entries[i];
    if (entry.element.id == "")
      entry.element.id = "toc" + i;
    var a = document.createElement("a");
    a.href = "#" + entry.element.id;
    a.appendChild(document.createTextNode(entry.text));
    var div = document.createElement("div");
    div.appendChild(a);
    div.className = "toclevel" + entry.toclevel;
    toc.appendChild(div);
  }
}
/*]]>*/
</script>
<title>LuaGame Function Reference</title>
</head>
<body>
<div id="header">
<h1>LuaGame Function Reference</h1>
<div id="toc">
  <div id="toctitle">Table of Contents</div>
  <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
</div>
</div>
<h2>1. Conventions</h2>
<div class="sectionbody">
<p>Arguments and return values are formatted: <strong>name&lt;type&gt;</strong>.</p>
<p>A return value of <strong>&lt;varying&gt;</strong> means that the function can
return a variable number of arguments. This will usually
be explained in the description of the function.</p>
</div>
<h2>2. Video</h2>
<div class="sectionbody">
<h3>2.1. image&lt;SDL_Surface*&gt; get_image(path&lt;string&gt;)</h3>
<p>Returns an SDL_Surface* to the image referenced by <strong>path</strong>.
If image has not been loaded before, it is loaded. If it has,
the pointer is returned.</p>
<h3>2.2. release_image(path&lt;string&gt;)</h3>
<p>Causes a loaded image to be freed from memory.
This is especially useful if one loads an image that is
only used for a small portion of the game because normally, an image
will stay loaded in memory forever.</p>
<h3>2.3. update_screen()</h3>
<p>Causes the screen surface in video memory to be updated from
the backbuffer or surface in main memory. This is basically
a call to <em>SDL_Flip()</em>.</p>
<h3>2.4. blit(image&lt;SDL_Surface*&gt;, x&lt;int&gt;, y&lt;int&gt;, rotation&lt;double&gt;, reposition&lt;bool&gt;, smoothing&lt;bool&gt;)</h3>
<p>Blits <strong>image</strong> to the screen at position <strong>(x, y)</strong>. If <strong>rotation</strong> is non-zero, the image will be rotated on the fly.
If <strong>reposition</strong> is true, the rotated image will be re-centered (you probably want this). <strong>Smoothing</strong> is whether or
not linear interpolation should be used (looks pretty but eats CPU).</p>
<h3>2.5. blit_frame(image&lt;SDL_Surface*&gt;, x&lt;int&gt;, y&lt;int&gt;, frames&lt;int&gt;, frame_num&lt;int&gt;)</h3>
<p>Blits frame <strong>frame_num</strong> to the screen at position <strong>(x, y)</strong> from <strong>image</strong> with <strong>frames</strong> number of frames.</p>
<h3>2.6. show_cursor(show&lt;bool&gt;)</h3>
<p>Turns on/off the display of the cursor.</p>
<h3>2.7. fill_screen(R&lt;int&gt;, G&lt;int&gt;, B&lt;int&gt;)</h3>
<p>Fills the screen with the color specified by the rgb triplet <strong>(R,G,B)</strong>.</p>
<h3>2.8. delete_image(image&lt;SDL_Surface*&gt;)</h3>
<p>This effectively calls SDL_FreeSurface() on <strong>image</strong>. This function
should <em>never</em> be used on an image loaded using <em>get_image()</em>.</p>
<h3>2.9. rz_image&lt;SDL_Surface*&gt;, w&lt;int&gt;, h&lt;int&gt; rotzoom(image&lt;SDL_Surface*&gt;, angle&lt;double&gt;, zoom&lt;double&gt;, smooth&lt;bool&gt;)</h3>
<p>Returns a rotated and/or zoomed version of <strong>image</strong> and also the width <strong>w</strong> and height <strong>h</strong> of the rotated/zoomed image.
<strong>Angle</strong> is specified in degrees. <strong>Zoom</strong> is the scaling factor. <strong>Smooth</strong> specifies whether linear interpolation
should be used when rotating/zooming the surface. Smoothing is expensive and should be used with care.
Surfaces returned by this function should be freed after use using <em>delete_image()</em>.</p>
</div>
<h2>3. Misc</h2>
<div class="sectionbody">
<h3>3.1. ticks&lt;int&gt; get_ticks()</h3>
<p>Returns the number of milliseconds since program intialization. This value overflows after 49 days (32-bit integer).</p>
<h3>3.2. delay(time&lt;int&gt;)</h3>
<p>Waits for <strong>time</strong> milliseconds and then returns.</p>
</div>
<h2>4. Input</h2>
<div class="sectionbody">
<h3>4.1. x&lt;int&gt;, y&lt;int&gt;, left&lt;bool&gt;, right&lt;bool&gt; mouse_state()</h3>
<p>Returns the absolute position (within the window) of the cursor.
It also returns the state of the left and right mouse buttons.
This function can be used to get the state of the mouse even when
and event manager is in use.</p>
<h3>4.2. num&lt;int&gt; num_joysticks()</h3>
<p>Returns the number of joysticks currently attached to the system.</p>
<h3>4.3. &lt;varying&gt; get_event()</h3>
<p>This function is used by the event manager to pass events
from SDL to Lua. It should never need to be explicitly
called by the programmer. It returns a varying number of
results.</p>
</div>
<h2>5. Sound</h2>
<div class="sectionbody">
<h3>5.1. sample&lt;Mix_Chunk*&gt; load_sample(path&lt;string&gt;)</h3>
<p>Loads a sample, specified by <strong>path</strong>, and returns a pointer to it.</p>
<h3>5.2. unload_sample(path&lt;string&gt;)</h3>
<p>Unloads a previously loaded sample specified by <strong>path</strong>.</p>
<h3>5.3. play_sample(sample&lt;Mix_Chunk*&gt;)</h3>
<p>Plays the sample specified by <strong>sample</strong>. The sample will play until completion.
Sample needs to have been previously loaded using load_sample().</p>
<h3>5.4. clear_samples()</h3>
<p>Unloads all loaded samples from memory.</p>
<h3>5.5. stop_samples()</h3>
<p>Stops the playback of all currently playing samples.</p>
<h3>5.6. play_music(path&lt;string&gt;, loops&lt;int&gt;)</h3>
<p>Plays music specified by <strong>path</strong>. Music will play <strong>loops</strong> times. If <strong>loops</strong> is -1 then it will loop continuously until stopped.</p>
<h3>5.7. stop_music()</h3>
<p>Stops the currently playing music.</p>
</div>
<h2>6. Drawing</h2>
<div class="sectionbody">
<h3>6.1. draw_pixel(x&lt;int&gt;, y&lt;int&gt;, R&lt;int&gt;, G&lt;int&gt;, B&lt;int&gt;, Alpha&lt;int&gt;)</h3>
<p>Draws a pixel of color <strong>rgb(R,G,B)</strong> at position <strong>(x,y)</strong>.</p>
<h3>6.2. draw_line(x1&lt;int&gt;, y1&lt;int&gt;, x2&lt;int&gt;, y2&lt;int&gt;, R&lt;int&gt;, G&lt;int&gt;, B&lt;int&gt;, Alpha&lt;int&gt;)</h3>
<p>Draws a line of color <strong>rgb(R,G,B)</strong> from <strong>(x1,y1)</strong> to <strong>(x2,y2)</strong>.</p>
<h3>6.3. draw_rect(x1&lt;int&gt;, y1&lt;int&gt;, x2&lt;int&gt;, y2&lt;int&gt;, R&lt;int&gt;, G&lt;int&gt;, B&lt;int&gt;, Alpha&lt;int&gt;)</h3>
<p>Draws a rectangle of color <strong>rgb(R,G,B)</strong> with top left corner <strong>(x1,y1)</strong> and bottom right corner <strong>(x2,y2)</strong>.</p>
<h3>6.4. draw_filled_rect(x1&lt;int&gt;, y1&lt;int&gt;, x2&lt;int&gt;, y2&lt;int&gt;, R&lt;int&gt;, G&lt;int&gt;, B&lt;int&gt;, Alpha&lt;int&gt;)</h3>
<p>Draws a filled rectangle of color <strong>rgb(R,G,B)</strong> with top left corner <strong>(x1,y1)</strong> and bottom right corner <strong>(x2,y2)</strong>.</p>
<h3>6.5. draw_circle(x&lt;int&gt;, y&lt;int&gt;, rad&lt;int&gt;, R&lt;int&gt;, G&lt;int&gt;, B&lt;int&gt;, Alpha&lt;int&gt;)</h3>
<p>Draws a circle of color <strong>rgb(R,G,B)</strong> with center at position <strong>(x,y)</strong> and radius of <strong>rad</strong>.</p>
<h3>6.6. draw_filled_circle(x&lt;int&gt;, y&lt;int&gt;, rad&lt;int&gt;, R&lt;int&gt;, G&lt;int&gt;, B&lt;int&gt;, Alpha&lt;int&gt;)</h3>
<p>Draws a filled circle of color <strong>rgb(R,G,B)</strong> with center at position <strong>(x,y)</strong> and radius of <strong>rad</strong>.</p>
<h3>6.7. draw_ellipse(x&lt;int&gt;, y&lt;int&gt;, x_rad&lt;int&gt;, y_rad&lt;int&gt;, R&lt;int&gt;, G&lt;int&gt;, B&lt;int&gt;, Alpha&lt;int&gt;)</h3>
<p>Draws an ellipse of color <strong>rgb(R,G,B)</strong> with center at position <strong>(x,y)</strong>, x radius of <strong>x_rad</strong> and y radius of <strong>y_rad</strong>.</p>
<h3>6.8. draw_filled_ellipse(x&lt;int&gt;, y&lt;int&gt;, x_rad&lt;int&gt;, y_rad&lt;int&gt;, R&lt;int&gt;, G&lt;int&gt;, B&lt;int&gt;, Alpha&lt;int&gt;)</h3>
<p>Draws a filled ellipse of color <strong>rgb(R,G,B)</strong> with center at position <strong>(x,y)</strong>, x radius of <strong>x_rad</strong> and y radius of <strong>y_rad</strong>.</p>
</div>
<h2>7. Font</h2>
<div class="sectionbody">
<h3>7.1. font&lt;TTF_Font*&gt; load_font(path&lt;string&gt;, size&lt;int&gt;)</h3>
<p>Loads a font specified by <strong>path</strong> at size <strong>size</strong>.</p>
<h3>7.2. unload_font(font&lt;TTF_Font*&gt;)</h3>
<p>Unloads a font specified by <strong>font</strong>.</p>
<h3>7.3. w&lt;int&gt;, h&lt;int&gt; rendered_string_size(font&lt;TTF_Font*&gt;, text&lt;string&gt;)</h3>
<p>Returns the width <strong>w</strong> and height <strong>h</strong> of the string <strong>text</strong> as rendered in <strong>font</strong>.</p>
<h3>7.4. txt_image&lt;SDL_Surface*&gt; render_string(font&lt;TTF_Font*&gt;, text&lt;string&gt;, R&lt;int&gt;, G&lt;int&gt;, B&lt;int&gt;)</h3>
<p>Renders string <strong>text</strong> in the specified <strong>font</strong> and color <strong>rgb(R,G,B)</strong> and returns it as an SDL_Surface.</p>
</div>
<h2>8. Instrumentation</h2>
<div class="sectionbody">
<p>These functions are written in Lua, but they belong here more than anywhere else.</p>
<h3>8.1. instr_begin(id&lt;string&gt;)</h3>
<p>Begins tracking the time between this call and the end tracking call for <strong>id</strong>.
Also keeps track of how many times it has been called (good for profiling).</p>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="./images/icons/note.png" alt="Note" />
</td>
<td class="content">Calls for the same id cannot be nested. This would result in the timer being
reset for the id, which means that the statistics will be wrong. An error will be
thrown if this is attempted.</td>
</tr></table>
</div>
<h3>8.2. instr_end(id&lt;string&gt;)</h3>
<p>Ends tracking for <strong>id</strong> and adds the time between the begin call and this one to
the total execution time for <strong>id</strong>.</p>
<h3>8.3. instr_track(id&lt;string&gt;, val&lt;number&gt;)</h3>
<p>Adds an entry to the value tracking table for <strong>id</strong> of value <strong>val</strong>.</p>
<h3>8.4. instr_stats()</h3>
<p>Prints out in a nice formatted way (with colors) the statistics for the time
tracking and the value tracking.</p>
<h3>8.5. instr_log(msg&lt;string&gt;, &#8230;&lt;strings&gt;)</h3>
<p>Adds an entry, <strong>msg</strong>, to the log, recording the time since start of execution.
The varying argument at the end is a number of strings that specify message
classes. Message classes are optional.</p>
<h3>8.6. instr_print_log(&#8230;&lt;strings&gt;)</h3>
<p>Prints out the log entries that match all specified classes. If no classes are
specified then it prints out all messages. Prints in ascending order of time recorded.</p>
</div>
<div id="footer">
<div id="footer-text">
Last updated 09-Jan-2008 19:32:58 EDT
</div>
</div>
</body>
</html>
